Restructure developer onboarding #303

nenharper · 2025-09-09T11:33:22Z

The goal of this pull request is to restructure the developer onboarding on Harper, so that they go from zero to first Harper app very quickly.

As a result, I've removed other docs pages that don't accelerate onboarding (but contribute to Harper knowledge) into a different section called "Foundations of Harper"

I also added a Harper architecture page and replaced the diagram.

Ethan-Arrowood

good progress!

versioned_docs/version-4.6/foundations/core-concepts.md

versioned_docs/version-4.6/foundations/use-cases.md

versioned_docs/version-4.6/getting-started/installation.md

Co-authored-by: Ethan Arrowood <[email protected]>

Ethan-Arrowood · 2025-09-15T19:17:02Z

docs/getting-started/installation.md

There needs to be links on this page to the documentation for our other config options. We want those searching for more specific installation instructions to easily find their way to our configuration information too.

docs/foundations/use-cases.md

docs/foundations/harper-architecture.md

Co-authored-by: Ethan Arrowood <[email protected]>

kriszyp

This looks a good direction, the "foundations" section looks like it could be really helpful.

kriszyp · 2025-09-16T02:44:32Z

docs/foundations/core-concepts.md

+💡 **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place.
+:::
+
+## Extensions (a type of Component)


Extensions and Plugins are not different types of components, they are the same type of component: a component designed to be used by other components/apps, not standalone. Plugin is just the new name for this type of component and the name for the new API for configuring this type of component and interacting with the dependent application. Really, the examples listed below are plugins as well (that use the old extension API).

kriszyp · 2025-09-16T02:44:55Z

docs/foundations/harper-architecture.md

+At a high level:
+
+- **Core services** handle data, networking, and files.
+- **Extensions** layer in reusable features (REST, GraphQL, Next.js, etc.).


kriszyp · 2025-09-16T02:45:56Z

docs/foundations/harper-architecture.md

+
+- **Database** → Fast storage, queries, and transactions.
+- **Networking** → REST/HTTP, WebSockets, MQTT, and cluster communication.
+- **File system** → File operations and serving static assets.


Harper does not ship with a file system. An operating system ships with a file system, along with thousands of other primitives. But we aren't defining an OS here and "file system" is not a meaningful part of Harper. A more important essential service is our component management system.

I added more comments to the discussion around the diagram as that is where these came from. In short, I used these terms not for their technical accuracy but for there general purposeness for first-time readers.

kriszyp · 2025-09-16T02:47:38Z

docs/foundations/harper-architecture.md

+- Guaranteed consistency at commit.
+
+:::info
+💡 **Why it matters:** You don’t have to think about database race conditions or half-finished writes—Harper guarantees integrity by default.


kriszyp · 2025-09-16T02:49:01Z

docs/foundations/harper-architecture.md

+
+Extensions are Harper’s plug-in modules. They add reusable features to applications and can depend on each other.
+
+Here are a few common examples: 


Is this a little redundant with the coverage of plugins in core concepts? Would it be more helpful to describe the architecture of the root configuration of components and the transitive configuration and dependency of components?

docs/foundations/use-cases.md

static/img/v4.4/harper-architecture.png

kriszyp · 2025-09-16T03:01:53Z

versioned_docs/version-4.5/foundations/core-concepts.md

Someday I would like to move the getting started guide outside the versioned docs, but that is beyond the scope of this PR.

kriszyp

A couple comments, but this is looking great!

docs/getting-started/installation.md

static/img/v4.4/harper-architecture.png

Ethan-Arrowood

Okay, I've kept all my feedback to the docs/ files and I assume we'll copy those to the versions later.

In general this is making great progress. Almost there. I wasn't sure at first we wanted to use "plugins" so prominently, and I'm totally happy with that change. Lets make sure we are consistent then.

docs/foundations/core-concepts.md

Ethan-Arrowood · 2025-09-17T20:38:33Z

docs/getting-started/installation.md

+✅ Quick check: open http://localhost:9925 or run:
+
+```bash
+curl http://localhost:9925/health
+```


Like what happens if the user had selected prod? Would these still work or do they need to try https instead?

Do they need to try https?

That is my point; these installation instructions are missing the nuance of the actual user experience of setting up Harper. If the user selected prod defaults during installation then yes they would need to use https. But these docs do not explain that.

I have a comment further up that mentions this and how we should go about fixing this section

docs/getting-started/installation.md

static/img/v4.4/harper-architecture.png

release-notes-data.json

Co-authored-by: Ethan Arrowood <[email protected]>

docs/getting-started/installation.md

Ethan-Arrowood

Almost there. Please remember to keep changes to the files within docs/ as those are the only ones I'm paying attention too right now. As soon as we are satisfied with those pages, you can copy them over to the versioned_docs/* paths.

docs/foundations/core-concepts.md

docs/getting-started/installation.md

kriszyp · 2025-10-03T12:33:09Z

docs/foundations/core-concepts.md

+
+Examples you’ll see in the ecosystem include:
+
+- **Built in extensions**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) for database and table definitions, [rest](../reference/components/built-in-extensions#rest) for RESTful access to your data, and [static](../reference/components/built-in-extensions#static) for serving files or frontend assets.


Should we use "plugins" here and below?

docs/foundations/core-concepts.md

static/img/v4.4/harper-architecture.png

Co-authored-by: Ethan Arrowood <[email protected]>

Ethan-Arrowood

Okay I'm satisfied with this now. I didn't look too closely but I assume the version directories match the docs/ one.

Restructure developer onboarding

f4a6fc3

nenharper requested review from Ethan-Arrowood and alekshaugom September 9, 2025 11:33

Made docs more narrative

12db91b

Ethan-Arrowood reviewed Sep 10, 2025

View reviewed changes

nenharper and others added 9 commits September 10, 2025 16:24

Update versioned_docs/version-4.6/getting-started/installation.md

d33ce4b

Co-authored-by: Ethan Arrowood <[email protected]>

Update versioned_docs/version-4.6/foundations/core-concepts.md

0f88de0

Co-authored-by: Ethan Arrowood <[email protected]>

Update versioned_docs/version-4.6/foundations/core-concepts.md

2e79eca

Co-authored-by: Ethan Arrowood <[email protected]>

Update versioned_docs/version-4.6/foundations/core-concepts.md

5aa46a1

Co-authored-by: Ethan Arrowood <[email protected]>

Update versioned_docs/version-4.6/getting-started/installation.md

1f9d2ca

Co-authored-by: Ethan Arrowood <[email protected]>

Update versioned_docs/version-4.6/getting-started/installation.md

ea73dfb

Co-authored-by: Ethan Arrowood <[email protected]>

Update versioned_docs/version-4.6/foundations/use-cases.md

632a1f1

Co-authored-by: Ethan Arrowood <[email protected]>

Address PR comment

7e4fa6f

Replicate onboarding across versions

5a54dbc

nenharper marked this pull request as ready for review September 15, 2025 15:57

nenharper requested a review from Ethan-Arrowood September 15, 2025 15:58

Ethan-Arrowood reviewed Sep 15, 2025

View reviewed changes

nenharper and others added 5 commits September 15, 2025 14:57

Update versioned_docs/version-4.6/foundations/core-concepts.md

9cf0354

Co-authored-by: Ethan Arrowood <[email protected]>

Address PR comments

7857ec6

Update docs/foundations/use-cases.md

e6a2074

Co-authored-by: Ethan Arrowood <[email protected]>

Address PR comments

4109d68

Fix format

75096a1

nenharper requested a review from Ethan-Arrowood September 15, 2025 21:37

Address more comments

0d4b2df

kriszyp requested changes Sep 16, 2025

View reviewed changes

Address more comments

1b54e32

nenharper requested a review from kriszyp September 16, 2025 07:17

nenharper added 3 commits September 16, 2025 09:25

Update diagrams

b14f6e4

After running npx prettier

1ee0106

Fixed broken links

f933fd9

nenharper added 4 commits September 16, 2025 10:39

Fixed broken links

852f20e

Fixed broken links

397b096

Fixed broken links

c11fa68

Fixed broken links

1a43272

kriszyp reviewed Sep 17, 2025

View reviewed changes

docs/getting-started/installation.md Show resolved Hide resolved

static/img/v4.4/harper-architecture.png Show resolved Hide resolved

Address PR comments

39239bf

nenharper requested a review from kriszyp September 17, 2025 20:23

Ethan-Arrowood reviewed Sep 17, 2025

View reviewed changes

Ethan-Arrowood mentioned this pull request Sep 17, 2025

Update diagram to better reflect Harper architecture #318

Closed

nenharper and others added 6 commits September 17, 2025 17:23

Update docs/foundations/core-concepts.md

dd169b1

Co-authored-by: Ethan Arrowood <[email protected]>

Update docs/foundations/core-concepts.md

25d6bb2

Co-authored-by: Ethan Arrowood <[email protected]>

Update docs/foundations/core-concepts.md

1b9326c

Co-authored-by: Ethan Arrowood <[email protected]>

Address comments

014288f

Address comments

da6a146

Fix broken links

3b361cc

nenharper requested a review from Ethan-Arrowood September 24, 2025 05:31

kriszyp reviewed Sep 24, 2025

View reviewed changes

docs/getting-started/installation.md Outdated Show resolved Hide resolved

Update docker

e69b730

nenharper requested a review from kriszyp September 29, 2025 16:26

Ethan-Arrowood reviewed Sep 29, 2025

View reviewed changes

docs/foundations/core-concepts.md Outdated Show resolved Hide resolved

docs/getting-started/installation.md Show resolved Hide resolved

kriszyp reviewed Oct 3, 2025

View reviewed changes

nenharper and others added 3 commits October 3, 2025 10:51

Update docs/foundations/core-concepts.md

1627d4d

Co-authored-by: Ethan Arrowood <[email protected]>

Address PR comments

16259f6

Address PR comments

6476c5f

nenharper requested a review from Ethan-Arrowood October 3, 2025 18:33

Ethan-Arrowood approved these changes Oct 6, 2025

View reviewed changes

kriszyp approved these changes Oct 7, 2025

View reviewed changes

Ethan-Arrowood merged commit ade07fd into main Oct 7, 2025
5 checks passed

Ethan-Arrowood deleted the nenne/harper-onboarding branch October 7, 2025 21:34


		Extensions are Harper’s plug-in modules. They add reusable features to applications and can depend on each other.

		Here are a few common examples:


		Examples you’ll see in the ecosystem include:

		- Built in extensions: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) for database and table definitions, [rest](../reference/components/built-in-extensions#rest) for RESTful access to your data, and [static](../reference/components/built-in-extensions#static) for serving files or frontend assets.

Restructure developer onboarding #303

Restructure developer onboarding #303

Uh oh!

Conversation

nenharper commented Sep 9, 2025

Uh oh!

Ethan-Arrowood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Ethan-Arrowood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ethan-Arrowood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!